[CI][Docs] Add scheduled Sphinx link check for docs by MrZ20 · Pull Request #8273 · vllm-project/vllm-ascend

MrZ20 · 2026-04-15T02:41:23Z

What this PR does / why we need it?

This PR adds a scheduled documentation link check workflow to catch broken links
and unexpected redirects in the Sphinx docs on a regular basis.

Main changes:

add a GitHub Actions workflow to run make -C docs linkcheck weekly and on manual trigger
configure Sphinx linkcheck options in docs/source/conf.py to reduce flaky CI failures
document how to run the docs link check locally and where to find the generated reports
fix link in docs

This helps us detect documentation link issues earlier and makes docs maintenance
more proactive and repeatable.

In docs/source/community/contributors.md, delete:

| 17 | [@dependabot[bot]](https://github.com/dependabot[bot]) | 2025/02/27 | [a5564ed](https://github.com/vllm-project/vllm-ascend/commit/a5564ed5d8fd9818936a22d9ea35951a27513b4c) |

| 149 | [@invalid-email-address](https://github.com/invalid-email-address) | 2025/09/14 | [c9da5de](https://github.com/vllm-project/vllm-ascend/commit/c9da5dea5c271187c0119848ede9c0518a0c41b2) |

| 207 | [@Copilot](https://github.com/Copilot) | 2025/11/11 | [24bca67](https://github.com/vllm-project/vllm-ascend/commit/24bca674412b56418c94bda7d659105315505a8e) |

| 292 | [@nomewang](https://github.com/nomewang) | 2026/01/12 | [348cdf9](https://github.com/vllm-project/vllm-ascend/commit/348cdf98aad7ae9b399bf8481fcf2bb3baa6a636) |

Does this PR introduce any user-facing change?

No user-facing runtime change.
This only affects documentation validation and contributor workflow.

How was this patch tested?

Verified the workflow definition and Sphinx linkcheck-related configuration changes
Added local usage instructions in:
- docs/source/developer_guide/contribution/testing.md

If needed, the check can be run locally with:

make -C docs linkcheck SPHINXOPTS="-W --keep-going"

vLLM version:
vLLM main: https://github.com/vllm-project/vllm/commit/v0.19.0

github-actions · 2026-04-15T02:41:37Z

👋 Hi! Thank you for contributing to the vLLM Ascend project. The following points will speed up your PR merge:‌‌

A PR should do only one thing, smaller PRs enable faster reviews.
Every PR should include unit tests and end-to-end tests ‌to ensure it works and is not broken by other future PRs.
Write the commit message by fulfilling the PR description to help reviewer and future developers understand.

If CI fails, you can run linting and testing checks locally according Contributing and Testing.

gemini-code-assist · 2026-04-15T02:41:41Z

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the documentation maintenance process by implementing an automated link verification system. By integrating a scheduled CI workflow and refining Sphinx configuration, the project can proactively detect and resolve broken external links, ensuring the reliability of the documentation for all users.

Highlights

Automated Link Validation: Introduced a new GitHub Actions workflow to perform weekly scheduled checks on documentation links to identify broken URLs and redirects.
Sphinx Configuration: Updated docs/source/conf.py with robust linkcheck settings, including timeout, retry logic, and exclusion patterns for local service endpoints to minimize CI flakiness.
Developer Documentation: Added instructions to the testing guide on how to execute the link check locally and where to locate the generated output reports.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Ignored Files

Ignored by pattern: .github/workflows/** (1)
- .github/workflows/schedule_docs_linkcheck.yaml

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request introduces a scheduled Sphinx link check to the documentation workflow, including configuration in docs/source/conf.py and local usage instructions in the developer guide. Feedback was provided regarding adherence to the repository's PR title and summary style guide, increasing the linkcheck_timeout to prevent flaky CI failures, and correcting a potentially overly specific IP address in the linkcheck_ignore list.

gemini-code-assist · 2026-04-15T02:43:38Z

+# sites render anchors dynamically, which makes anchor checks flaky in CI.
+linkcheck_anchors = False
+linkcheck_retries = 2
+linkcheck_timeout = 10


A timeout of 10 seconds is quite low for external link checks and may lead to flaky CI failures when remote servers are slow to respond. Increasing this to the Sphinx default of 30 seconds or higher is recommended for better stability.

Suggested change

linkcheck_timeout = 10

linkcheck_timeout = 30

References

Avoid low timeouts in CI configurations to prevent flaky builds caused by external network latency.

Signed-off-by: MrZ20 <2609716663@qq.com>

Signed-off-by: MrZ20 <2609716663@qq.com> link check Signed-off-by: MrZ20 <2609716663@qq.com> fix Signed-off-by: MrZ20 <2609716663@qq.com>

Signed-off-by: MrZ20 <2609716663@qq.com>

@invalid-email-address

### What this PR does / why we need it? This PR adds a scheduled documentation link check workflow to catch broken links and unexpected redirects in the Sphinx docs on a regular basis. Main changes: - add a GitHub Actions workflow to run `make -C docs linkcheck` weekly and on manual trigger - configure Sphinx `linkcheck` options in `docs/source/conf.py` to reduce flaky CI failures - document how to run the docs link check locally and where to find the generated reports - fix link in docs This helps us detect documentation link issues earlier and makes docs maintenance more proactive and repeatable. In docs/source/community/**contributors.md**, delete: ``` | 17 | [@dependabot[bot]](https://github.com/dependabot[bot]) | 2025/02/27 | [a5564ed](vllm-project@a5564ed) | | 149 | [@invalid-email-address](https://github.com/invalid-email-address) | 2025/09/14 | [c9da5de](vllm-project@c9da5de) | | 207 | [@Copilot](https://github.com/Copilot) | 2025/11/11 | [24bca67](vllm-project@24bca67) | | 292 | [@nomewang](https://github.com/nomewang) | 2026/01/12 | [348cdf9](vllm-project@348cdf9) | ``` ### Does this PR introduce _any_ user-facing change? No user-facing runtime change. This only affects documentation validation and contributor workflow. ### How was this patch tested? - Verified the workflow definition and Sphinx linkcheck-related configuration changes - Added local usage instructions in: - `docs/source/developer_guide/contribution/testing.md` If needed, the check can be run locally with: ```bash make -C docs linkcheck SPHINXOPTS="-W --keep-going" ``` - vLLM version: - vLLM main: https://github.com/vllm-project/vllm/commit/v0.19.0 --------- Signed-off-by: MrZ20 <2609716663@qq.com> Signed-off-by: zouyida2052 <zouyida2002@gmail.com>

@invalid-email-address

### What this PR does / why we need it? This PR adds a scheduled documentation link check workflow to catch broken links and unexpected redirects in the Sphinx docs on a regular basis. Main changes: - add a GitHub Actions workflow to run `make -C docs linkcheck` weekly and on manual trigger - configure Sphinx `linkcheck` options in `docs/source/conf.py` to reduce flaky CI failures - document how to run the docs link check locally and where to find the generated reports - fix link in docs This helps us detect documentation link issues earlier and makes docs maintenance more proactive and repeatable. In docs/source/community/**contributors.md**, delete: ``` | 17 | [@dependabot[bot]](https://github.com/dependabot[bot]) | 2025/02/27 | [a5564ed](vllm-project@a5564ed) | | 149 | [@invalid-email-address](https://github.com/invalid-email-address) | 2025/09/14 | [c9da5de](vllm-project@c9da5de) | | 207 | [@Copilot](https://github.com/Copilot) | 2025/11/11 | [24bca67](vllm-project@24bca67) | | 292 | [@nomewang](https://github.com/nomewang) | 2026/01/12 | [348cdf9](vllm-project@348cdf9) | ``` ### Does this PR introduce _any_ user-facing change? No user-facing runtime change. This only affects documentation validation and contributor workflow. ### How was this patch tested? - Verified the workflow definition and Sphinx linkcheck-related configuration changes - Added local usage instructions in: - `docs/source/developer_guide/contribution/testing.md` If needed, the check can be run locally with: ```bash make -C docs linkcheck SPHINXOPTS="-W --keep-going" ``` - vLLM version: - vLLM main: https://github.com/vllm-project/vllm/commit/v0.19.0 --------- Signed-off-by: MrZ20 <2609716663@qq.com>

@invalid-email-address

### What this PR does / why we need it? This PR adds a scheduled documentation link check workflow to catch broken links and unexpected redirects in the Sphinx docs on a regular basis. Main changes: - add a GitHub Actions workflow to run `make -C docs linkcheck` weekly and on manual trigger - configure Sphinx `linkcheck` options in `docs/source/conf.py` to reduce flaky CI failures - document how to run the docs link check locally and where to find the generated reports - fix link in docs This helps us detect documentation link issues earlier and makes docs maintenance more proactive and repeatable. In docs/source/community/**contributors.md**, delete: ``` | 17 | [@dependabot[bot]](https://github.com/dependabot[bot]) | 2025/02/27 | [a5564ed](vllm-project@a5564ed) | | 149 | [@invalid-email-address](https://github.com/invalid-email-address) | 2025/09/14 | [c9da5de](vllm-project@c9da5de) | | 207 | [@Copilot](https://github.com/Copilot) | 2025/11/11 | [24bca67](vllm-project@24bca67) | | 292 | [@nomewang](https://github.com/nomewang) | 2026/01/12 | [348cdf9](vllm-project@348cdf9) | ``` ### Does this PR introduce _any_ user-facing change? No user-facing runtime change. This only affects documentation validation and contributor workflow. ### How was this patch tested? - Verified the workflow definition and Sphinx linkcheck-related configuration changes - Added local usage instructions in: - `docs/source/developer_guide/contribution/testing.md` If needed, the check can be run locally with: ```bash make -C docs linkcheck SPHINXOPTS="-W --keep-going" ``` - vLLM version: - vLLM main: https://github.com/vllm-project/vllm/commit/v0.19.0 --------- Signed-off-by: MrZ20 <2609716663@qq.com> Signed-off-by: PiratePai <416932041@qq.com>

@invalid-email-address

### What this PR does / why we need it? This PR adds a scheduled documentation link check workflow to catch broken links and unexpected redirects in the Sphinx docs on a regular basis. Main changes: - add a GitHub Actions workflow to run `make -C docs linkcheck` weekly and on manual trigger - configure Sphinx `linkcheck` options in `docs/source/conf.py` to reduce flaky CI failures - document how to run the docs link check locally and where to find the generated reports - fix link in docs This helps us detect documentation link issues earlier and makes docs maintenance more proactive and repeatable. In docs/source/community/**contributors.md**, delete: ``` | 17 | [@dependabot[bot]](https://github.com/dependabot[bot]) | 2025/02/27 | [a5564ed](vllm-project@a5564ed) | | 149 | [@invalid-email-address](https://github.com/invalid-email-address) | 2025/09/14 | [c9da5de](vllm-project@c9da5de) | | 207 | [@Copilot](https://github.com/Copilot) | 2025/11/11 | [24bca67](vllm-project@24bca67) | | 292 | [@nomewang](https://github.com/nomewang) | 2026/01/12 | [348cdf9](vllm-project@348cdf9) | ``` ### Does this PR introduce _any_ user-facing change? No user-facing runtime change. This only affects documentation validation and contributor workflow. ### How was this patch tested? - Verified the workflow definition and Sphinx linkcheck-related configuration changes - Added local usage instructions in: - `docs/source/developer_guide/contribution/testing.md` If needed, the check can be run locally with: ```bash make -C docs linkcheck SPHINXOPTS="-W --keep-going" ``` - vLLM version: - vLLM main: https://github.com/vllm-project/vllm/commit/v0.19.0 --------- Signed-off-by: MrZ20 <2609716663@qq.com> Signed-off-by: yangzhe-2026 <yangzhe@isrc.iscas.ac.cn>

@invalid-email-address

### What this PR does / why we need it? This PR adds a scheduled documentation link check workflow to catch broken links and unexpected redirects in the Sphinx docs on a regular basis. Main changes: - add a GitHub Actions workflow to run `make -C docs linkcheck` weekly and on manual trigger - configure Sphinx `linkcheck` options in `docs/source/conf.py` to reduce flaky CI failures - document how to run the docs link check locally and where to find the generated reports - fix link in docs This helps us detect documentation link issues earlier and makes docs maintenance more proactive and repeatable. In docs/source/community/**contributors.md**, delete: ``` | 17 | [@dependabot[bot]](https://github.com/dependabot[bot]) | 2025/02/27 | [a5564ed](vllm-project@a5564ed) | | 149 | [@invalid-email-address](https://github.com/invalid-email-address) | 2025/09/14 | [c9da5de](vllm-project@c9da5de) | | 207 | [@Copilot](https://github.com/Copilot) | 2025/11/11 | [24bca67](vllm-project@24bca67) | | 292 | [@nomewang](https://github.com/nomewang) | 2026/01/12 | [348cdf9](vllm-project@348cdf9) | ``` ### Does this PR introduce _any_ user-facing change? No user-facing runtime change. This only affects documentation validation and contributor workflow. ### How was this patch tested? - Verified the workflow definition and Sphinx linkcheck-related configuration changes - Added local usage instructions in: - `docs/source/developer_guide/contribution/testing.md` If needed, the check can be run locally with: ```bash make -C docs linkcheck SPHINXOPTS="-W --keep-going" ``` - vLLM version: - vLLM main: https://github.com/vllm-project/vllm/commit/v0.19.0 --------- Signed-off-by: MrZ20 <2609716663@qq.com> Signed-off-by: ZhuQi-seu <zhuqi12@huawei.com>

@invalid-email-address

### What this PR does / why we need it? This PR adds a scheduled documentation link check workflow to catch broken links and unexpected redirects in the Sphinx docs on a regular basis. Main changes: - add a GitHub Actions workflow to run `make -C docs linkcheck` weekly and on manual trigger - configure Sphinx `linkcheck` options in `docs/source/conf.py` to reduce flaky CI failures - document how to run the docs link check locally and where to find the generated reports - fix link in docs This helps us detect documentation link issues earlier and makes docs maintenance more proactive and repeatable. In docs/source/community/**contributors.md**, delete: ``` | 17 | [@dependabot[bot]](https://github.com/dependabot[bot]) | 2025/02/27 | [a5564ed](vllm-project@a5564ed) | | 149 | [@invalid-email-address](https://github.com/invalid-email-address) | 2025/09/14 | [c9da5de](vllm-project@c9da5de) | | 207 | [@Copilot](https://github.com/Copilot) | 2025/11/11 | [24bca67](vllm-project@24bca67) | | 292 | [@nomewang](https://github.com/nomewang) | 2026/01/12 | [348cdf9](vllm-project@348cdf9) | ``` ### Does this PR introduce _any_ user-facing change? No user-facing runtime change. This only affects documentation validation and contributor workflow. ### How was this patch tested? - Verified the workflow definition and Sphinx linkcheck-related configuration changes - Added local usage instructions in: - `docs/source/developer_guide/contribution/testing.md` If needed, the check can be run locally with: ```bash make -C docs linkcheck SPHINXOPTS="-W --keep-going" ``` - vLLM version: - vLLM main: https://github.com/vllm-project/vllm/commit/v0.19.0 --------- Signed-off-by: MrZ20 <2609716663@qq.com> Signed-off-by: nanxing <1014662416@qq.com>

@invalid-email-address

### What this PR does / why we need it? This PR adds a scheduled documentation link check workflow to catch broken links and unexpected redirects in the Sphinx docs on a regular basis. Main changes: - add a GitHub Actions workflow to run `make -C docs linkcheck` weekly and on manual trigger - configure Sphinx `linkcheck` options in `docs/source/conf.py` to reduce flaky CI failures - document how to run the docs link check locally and where to find the generated reports - fix link in docs This helps us detect documentation link issues earlier and makes docs maintenance more proactive and repeatable. In docs/source/community/**contributors.md**, delete: ``` | 17 | [@dependabot[bot]](https://github.com/dependabot[bot]) | 2025/02/27 | [a5564ed](vllm-project@a5564ed) | | 149 | [@invalid-email-address](https://github.com/invalid-email-address) | 2025/09/14 | [c9da5de](vllm-project@c9da5de) | | 207 | [@Copilot](https://github.com/Copilot) | 2025/11/11 | [24bca67](vllm-project@24bca67) | | 292 | [@nomewang](https://github.com/nomewang) | 2026/01/12 | [348cdf9](vllm-project@348cdf9) | ``` ### Does this PR introduce _any_ user-facing change? No user-facing runtime change. This only affects documentation validation and contributor workflow. ### How was this patch tested? - Verified the workflow definition and Sphinx linkcheck-related configuration changes - Added local usage instructions in: - `docs/source/developer_guide/contribution/testing.md` If needed, the check can be run locally with: ```bash make -C docs linkcheck SPHINXOPTS="-W --keep-going" ``` - vLLM version: - vLLM main: https://github.com/vllm-project/vllm/commit/v0.19.0 --------- Signed-off-by: MrZ20 <2609716663@qq.com>

@invalid-email-address

### What this PR does / why we need it? This PR adds a scheduled documentation link check workflow to catch broken links and unexpected redirects in the Sphinx docs on a regular basis. Main changes: - add a GitHub Actions workflow to run `make -C docs linkcheck` weekly and on manual trigger - configure Sphinx `linkcheck` options in `docs/source/conf.py` to reduce flaky CI failures - document how to run the docs link check locally and where to find the generated reports - fix link in docs This helps us detect documentation link issues earlier and makes docs maintenance more proactive and repeatable. In docs/source/community/**contributors.md**, delete: ``` | 17 | [@dependabot[bot]](https://github.com/dependabot[bot]) | 2025/02/27 | [1c2c5d9](vllm-project@1c2c5d9) | | 149 | [@invalid-email-address](https://github.com/invalid-email-address) | 2025/09/14 | [c9da5de](vllm-project@c9da5de) | | 207 | [@Copilot](https://github.com/Copilot) | 2025/11/11 | [24bca67](vllm-project@24bca67) | | 292 | [@nomewang](https://github.com/nomewang) | 2026/01/12 | [348cdf9](vllm-project@348cdf9) | ``` ### Does this PR introduce _any_ user-facing change? No user-facing runtime change. This only affects documentation validation and contributor workflow. ### How was this patch tested? - Verified the workflow definition and Sphinx linkcheck-related configuration changes - Added local usage instructions in: - `docs/source/developer_guide/contribution/testing.md` If needed, the check can be run locally with: ```bash make -C docs linkcheck SPHINXOPTS="-W --keep-going" ``` - vLLM version: - vLLM main: https://github.com/vllm-project/vllm/commit/v0.19.0 --------- Signed-off-by: MrZ20 <2609716663@qq.com>

github-actions Bot added documentation Improvements or additions to documentation ci/build labels Apr 15, 2026

gemini-code-assist Bot reviewed Apr 15, 2026

View reviewed changes

MrZ20 force-pushed the workflow_web branch 11 times, most recently from 911515e to e5be2b6 Compare April 21, 2026 10:22

MrZ20 marked this pull request as ready for review April 22, 2026 06:42

MrZ20 requested review from LCAIZJ, Yikun and wangxiyuan as code owners April 22, 2026 06:42

MrZ20 force-pushed the workflow_web branch 2 times, most recently from 5c753e0 to 60ab261 Compare April 22, 2026 08:09

Potabk reviewed Apr 22, 2026

View reviewed changes

Comment thread .github/workflows/schedule_doc_linkcheck.yaml Resolved

MrZ20 force-pushed the workflow_web branch 5 times, most recently from b0b4ac3 to e8081bb Compare April 23, 2026 08:58

MrZ20 added 2 commits April 24, 2026 15:44

v1

47144c0

Signed-off-by: MrZ20 <2609716663@qq.com>

push

435069e

Signed-off-by: MrZ20 <2609716663@qq.com>

MrZ20 added 10 commits April 24, 2026 15:44

add

8ad976d

Signed-off-by: MrZ20 <2609716663@qq.com>

fix

d94fd6f

Signed-off-by: MrZ20 <2609716663@qq.com>

add workflow

e9b0175

Signed-off-by: MrZ20 <2609716663@qq.com>

test

6ecbb7c

Signed-off-by: MrZ20 <2609716663@qq.com>

end

47c6f72

Signed-off-by: MrZ20 <2609716663@qq.com>

fix

cb3244c

Signed-off-by: MrZ20 <2609716663@qq.com>

modify

53fb337

Signed-off-by: MrZ20 <2609716663@qq.com>

add

d6438f0

Signed-off-by: MrZ20 <2609716663@qq.com>

modify

6bdc6c7

Signed-off-by: MrZ20 <2609716663@qq.com> link check Signed-off-by: MrZ20 <2609716663@qq.com> fix Signed-off-by: MrZ20 <2609716663@qq.com>

del

15453a9

Signed-off-by: MrZ20 <2609716663@qq.com>

MrZ20 force-pushed the workflow_web branch from e8081bb to 15453a9 Compare April 24, 2026 09:20

wangxiyuan merged commit dedb0d3 into vllm-project:main Apr 25, 2026
36 checks passed

MrZ20 deleted the workflow_web branch May 21, 2026 03:43

Navigation Menu

Repository navigation

[CI][Docs] Add scheduled Sphinx link check for docs - #8273

[CI][Docs] Add scheduled Sphinx link check for docs#8273
wangxiyuan merged 12 commits into
vllm-project:mainfrom
MrZ20:workflow_web

MrZ20 commented Apr 15, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Apr 15, 2026

Uh oh!

gemini-code-assist Bot commented Apr 15, 2026

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

Uh oh!

gemini-code-assist Bot Apr 15, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

MrZ20 commented Apr 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this PR does / why we need it?

Does this PR introduce any user-facing change?

How was this patch tested?

Uh oh!

github-actions Bot commented Apr 15, 2026

Uh oh!

gemini-code-assist Bot commented Apr 15, 2026

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

gemini-code-assist Bot Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

MrZ20 commented Apr 15, 2026 •

edited

Loading